Tighten cua-agent design seams: typed translator, declared channels - #21

Summary

Design-review follow-ups for packages/agent:

• Typed translator (no more silent misclicks): InternalComputerTranslator.executeBatch now takes the canonical CuaAction[] union with an exhaustive switch (never guard), replacing the Record<string, unknown> re-parsing layer. pi already validates tool arguments against the typebox schemas before execute, so the defensive toInt/stringOr fallbacks that could turn malformed input into a click at 0,0 are gone; a new canonical action type is now a compile error here instead of a runtime throw. The one remaining runtime guard is the documented button coercion (wire schemas keep button an open string; out-of-set values coerce to "left" per the CuaMouseButton contract). The duplicated button unions are deleted in favor of cua-ai's.
• Declared keepToolNames channel: cua-ai exports CuaSimpleStreamOptions (SimpleStreamOptions + keepToolNames), and CuaAgent's stream wrapper uses it — the as SimpleStreamOptions & {...} cast is gone, so the agent/adapter agreement is compiler-owned.
• One translator per runtime: CuaRuntimeController shares a single InternalComputerTranslator between the executor tools and the payload getScreenshot capability (previously two instances per runtime). createCuaComputerTools is unchanged for external composition.
• Conditional prepareNextTurn: the wrapper now returns undefined (stock pi behavior, no context rebuild) unless a user hook returns an update or a mid-run model assignment marks the runtime dirty — removing the every-turn context reconstruction and its silent-field-drop risk. The state proxy re-keys off the underlying state object's identity so it can't wrap a stale target.
• keys.ts reframed: comment + test name now state what the alias table is for — absorbing model nondeterminism in key naming (W3C names, shorthand, word-form punctuation) into Kernel's X11 vocabulary — rather than reading as provider-specific knowledge.
• README: the CuaAgentHarness quickstart now showcases the harness (session-backed turns, mid-session setModel provider switch, direct prompt() result handling — it returns the turn's final AssistantMessage) instead of branch-walking gymnastics; computerUseExtra is introduced with its rationale (not every provider's native vocabulary includes navigation; this is the provider-neutral escape hatch). Snippet typechecks against the built packages.
• docs/architecture.md: the ownership-boundary section now encodes the seam explicitly — provider differences arrive as CuaRuntimeSpec data, the agent supplies capabilities back via CuaPayloadContext, packages/agent/src contains no provider names/conditionals (grep-testable), with the deliberate exception for generic model imprecision absorbed by the translator.

Test plan

• New: full fake-stream tool-call turn (model emits toolCall → translator → mocked Kernel batch/screenshot → toolResult with image fed back to the second provider request)
• New: prepareNextTurn pass-through when nothing changed; one-shot turn update (new model + refreshed tools) after agent.state.model assignment, then pass-through again
• npm test -w @onkernel/cua-agent (28 passed, live excluded) and -w @onkernel/cua-ai (88 passed)
• npm run build both workspaces (tsdown) + monorepo tsc -b green
• README harness snippet extracted and typechecked against the built packages
• Live provider matrix (e2e.live.test.ts) — recommend a run before the next release since translator internals changed

🤖 Generated with Claude Code